<html>
<head><meta charset="utf-8"><title>macros named &quot;str&quot; considered harmful · rustdoc · Zulip Chat Archive</title></head>
<h2>Stream: <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/index.html">rustdoc</a></h2>
<h3>Topic: <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/macros.20named.20.22str.22.20considered.20harmful.html">macros named &quot;str&quot; considered harmful</a></h3>

<hr>

<base href="https://rust-lang.zulipchat.com">

<head><link href="https://rust-lang.github.io/zulip_archive/style.css" rel="stylesheet"></head>

<a name="224736870"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/macros%20named%20%22str%22%20considered%20harmful/near/224736870" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Mario Carneiro <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/macros.20named.20.22str.22.20considered.20harmful.html#224736870">(Feb 01 2021 at 14:57)</a>:</h4>
<p>I had to tear my project apart to find the cause of this bug. It turns out that a private macro in a completely separate module can cause intra doc links to break.</p>
<div class="codehilite" data-code-language="Rust"><pre><span></span><code><span class="k">mod</span> <span class="nn">bar</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">    </span><span class="fm">macro_rules!</span><span class="w"> </span><span class="kt">str</span><span class="w"> </span><span class="p">{()</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="p">{}}</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>

<span class="k">pub</span><span class="w"> </span><span class="k">mod</span> <span class="nn">foo</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">    </span><span class="k">use</span><span class="w"> </span><span class="n">std</span>::<span class="n">path</span>::<span class="p">{</span><span class="n">Path</span><span class="p">,</span><span class="w"> </span><span class="n">PathBuf</span><span class="p">};</span><span class="w"></span>

<span class="w">    </span><span class="k">pub</span><span class="w"> </span><span class="k">struct</span> <span class="nc">Foo</span><span class="p">(</span><span class="n">PathBuf</span><span class="p">);</span><span class="w"></span>
<span class="w">    </span><span class="k">impl</span><span class="w"> </span><span class="n">std</span>::<span class="n">ops</span>::<span class="n">Deref</span><span class="w"> </span><span class="k">for</span><span class="w"> </span><span class="n">Foo</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">        </span><span class="k">type</span> <span class="nc">Target</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">Path</span><span class="p">;</span><span class="w"></span>
<span class="w">        </span><span class="k">fn</span> <span class="nf">deref</span><span class="p">(</span><span class="o">&amp;</span><span class="bp">self</span><span class="p">)</span><span class="w"> </span>-&gt; <span class="kp">&amp;</span><span class="nc">Path</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="o">&amp;</span><span class="bp">self</span><span class="p">.</span><span class="mi">0</span><span class="w"> </span><span class="p">}</span><span class="w"></span>
<span class="w">    </span><span class="p">}</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>
</code></pre></div>
<p>If you run <code>cargo doc</code> on this, the documentation on <code>Foo::to_str()</code> coming from the deref impl, which contains</p>
<blockquote>
<p>Yields a <a href="http://str"><code>&amp;str</code></a> slice if the <code>Path</code> is valid unicode.</p>
</blockquote>
<p>will link directly to str (not the macro <code>str!</code>, just a broken link to the same directory). If you remove the macro it correctly links to the str documentation in the standard library.</p>



<a name="224741424"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/macros%20named%20%22str%22%20considered%20harmful/near/224741424" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Daniel Henry-Mantilla <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/macros.20named.20.22str.22.20considered.20harmful.html#224741424">(Feb 01 2021 at 15:26)</a>:</h4>
<p>(deleted)</p>



<a name="224756411"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/macros%20named%20%22str%22%20considered%20harmful/near/224756411" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/macros.20named.20.22str.22.20considered.20harmful.html#224756411">(Feb 01 2021 at 16:57)</a>:</h4>
<p><span class="user-mention" data-user-id="271719">@Mario Carneiro</span> this is a bug, rustdoc should check for this in <a href="https://github.com/rust-lang/rust/blob/70b18bc2cbac4712020019f5bf57c00905373205/src/librustdoc/passes/collect_intra_doc_links.rs#L1095-L1101">https://github.com/rust-lang/rust/blob/70b18bc2cbac4712020019f5bf57c00905373205/src/librustdoc/passes/collect_intra_doc_links.rs#L1095-L1101</a>. Can you open an issue?</p>



<a name="224757779"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/macros%20named%20%22str%22%20considered%20harmful/near/224757779" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/macros.20named.20.22str.22.20considered.20harmful.html#224757779">(Feb 01 2021 at 17:05)</a>:</h4>
<p>actually it's twice a bug because the deref documentation should be resolved in the original scope of <code>Path</code></p>



<a name="224758069"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/macros%20named%20%22str%22%20considered%20harmful/near/224758069" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Mario Carneiro <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/macros.20named.20.22str.22.20considered.20harmful.html#224758069">(Feb 01 2021 at 17:06)</a>:</h4>
<p><a href="https://github.com/rust-lang/rust/issues/81633">#81633</a></p>



<a name="224758367"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/macros%20named%20%22str%22%20considered%20harmful/near/224758367" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Mario Carneiro <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/macros.20named.20.22str.22.20considered.20harmful.html#224758367">(Feb 01 2021 at 17:08)</a>:</h4>
<p>Is it a bad idea to have macros named <code>str</code>? I was half expecting that not to work because of the name shadowing but rust didn't complain so I figured it was fine, bugs notwithstanding</p>



<a name="224758854"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/macros%20named%20%22str%22%20considered%20harmful/near/224758854" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/macros.20named.20.22str.22.20considered.20harmful.html#224758854">(Feb 01 2021 at 17:11)</a>:</h4>
<p>I mean it's probably <em>confusing</em> but I don't think it's <em>wrong</em></p>



<a name="224759072"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/macros%20named%20%22str%22%20considered%20harmful/near/224759072" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Mario Carneiro <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/macros.20named.20.22str.22.20considered.20harmful.html#224759072">(Feb 01 2021 at 17:13)</a>:</h4>
<p>Since it gets written <code>str!</code> most of the time it isn't normally a disambiguation hazard, although intra-doc links might be an exception</p>



<a name="224759340"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/macros%20named%20%22str%22%20considered%20harmful/near/224759340" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/macros.20named.20.22str.22.20considered.20harmful.html#224759340">(Feb 01 2021 at 17:14)</a>:</h4>
<p>intra-doc links should warn about ambiguity though</p>



<a name="224759363"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/macros%20named%20%22str%22%20considered%20harmful/near/224759363" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/macros.20named.20.22str.22.20considered.20harmful.html#224759363">(Feb 01 2021 at 17:14)</a>:</h4>
<p>you found an edge case where they didn't, but they should</p>



<a name="224792788"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/266220-rustdoc/topic/macros%20named%20%22str%22%20considered%20harmful/near/224792788" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Noah Lev <a href="https://rust-lang.github.io/zulip_archive/stream/266220-rustdoc/topic/macros.20named.20.22str.22.20considered.20harmful.html#224792788">(Feb 01 2021 at 21:20)</a>:</h4>
<p>Yes, they should make you explicitly use either <code>prim@str</code> or <code>str!</code> in this case.</p>



<hr><p>Last updated: Aug 07 2021 at 22:04 UTC</p>
</html>